<p class="Head1"><help:link Id="66513">Procedures and Functions</help:link></p>
<p class="Paragraph">The following provides a description of SUBS (procedures) and FUNCTIONS.</p>
</help:to-be-embedded>
<p class="Paragraph">Procedures and functions allow you to break a program into partial programs, and thus, maintain a structured overview.</p>
<p class="Paragraph">An advantage of SUBS and FUNCTIONS is that once you have developed a program code containing task components, you can use this code in different places in your project, but also in all future projects. To illustrate, please refer to the following sample program:</p>
<p class="TextInTable">You can copy this program from the <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> help and insert it directly into the IDE. To enter the program manually, select <span class="T1">Tools - Macro</span>, and type "Start" as the <span class="T1">Macro name</span>. Click <span class="T1">New</span> to switch to the IDE.</p>
</span></th></tr></table>
<p class="Paragraph"/>
<p class="PropText">option explicit</p>
<p class="PropText"/>
<p class="PropText">Sub Start</p>
<p class="PropText"/>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>Dim stext as String</p>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>Dim sInfoText1 as String</p>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>Dim sInfoText2 as String</p>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>Dim sInfoText3 as String</p>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>Dim sTitleText as String</p>
<p class="PropText"/>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>sInfoText1 = "Please enter your text"</p>
<p class="PropText"><text:tab-stop xmlns:text="http://openoffice.org/2000/text"/>sInfoText2 = "This text contains"</p>
<p class="Paragraph">If you start this program directly from the IDE, the program begins with the SUB "Start" (since it is at the first position). Within the procedure, the user is requested to enter a text. This text is then passed to the <span class="T1">WordCount</span> function which counts the number of spaces and returns the number of words contained in the text.</p>
<p class="Paragraph">The advantage of using functions is that the name (e.g., <span class="T1">WordCount</span>) indicates which function to perform, and if you need the function in another position within a program, you can simply call it again. However, the code appears only once, thus making the program code more compact and enabling a better overview.</p>
<p class="Head2">Passing Variables to SUBS or FUNCTIONS</p>
<p class="Paragraph">Variables can be passed to both SUBS or FUNCTIONS and used as fixed components of the <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Basic programming language, providing that the SUB or FUNCTION to be called expects the parameter. The declaration is as follows:</p>
<p class="PropText">SUB SubName(Parameter1 As Type, Parameter2 As Type,...)</p>
<p class="PropText"/>
<p class="PropText"/>
<p class="PropText">Program code</p>
<p class="PropText"/>
<p class="PropText"/>
<p class="PropText">END SUB</p>
<p class="Paragraph">Use the following command to call the SUB:</p>
<p class="Paragraph">Ensure that the parameters passed to a SUB are the same as those specified in the SUB declaration.</p>
<p class="Paragraph">The same process applies to FUNCTIONS, to return a function result. This result can be defined directly before reaching the end of the function by assigning the function name and a parameter to the value to be returned by the function. (see example).</p>
<p class="PropText">FUNCTION FunctionName(Parameter1 As Type, Parameter2 As Type,...) As Type</p>
<p class="Head3">Determining the Return Value of a FUNCTION</p>
<p class="Paragraph">As you can see from the FUNCTION definition in the example above, the type of return value must be specified. As with variables, simply include a type-declaration character after the function name, or the type indicated by "As" and the corresponding key word at the end of the parameter list. Thus, the definition line may appear in one of the following variations :</p>
<p class="PropText">Function WordCount(WordText as String) as Integer</p>
<p class="Head3">Passing Variables as Value and Reference</p>
<p class="Paragraph">A very important distinction to keep in mind when passing variables to FUNCTIONS or SUBS <text:s text:c="" xmlns:text="http://openoffice.org/2000/text"/>is the difference between variables passed as a reference or as a value.</p>
<p class="Paragraph">Unless otherwise specified, a variable is always passed as a reference to a FUNCTION or SUB. This means that when you modify a variable within a SUB or FUNCTION, the variable passed in the code to be called by the SUB or FUNCTION is correspondingly modified. In the above example, modify the sample program as follows:</p>
<p class="Paragraph">Insert an additional command line in the SUB "Start" after the <span class="T1">Print</span> command:</p>
<p class="PropText">PRINT stext</p>
<p class="Paragraph">Insert an additional command line before the "End Function" line in the FUNCTION <span class="T1">WordCount%</span> :</p>
<p class="Paragraph">Now, start the program and enter a text. <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Basic returns the number of spaces and prints the content of the variable <span class="T2"><text:s text:c="" xmlns:text="http://openoffice.org/2000/text"/>text$ </span>: "Function ended". The content of this variable appears to be modified, but not by the main program, rather by the FUNCTION <span class="T1">WordCount%</span>. Since the variable was passed directly to the function, it was able to modify the content of the variable, even though it was only valid in the main program.</p>
<p class="Paragraph">If you want to prevent this from occurring, insert the key word "ByVal" (By Value) before the passed variable when you call a SUB or FUNCTION. Modify the first <span class="T1">Print</span> line in the SUB "Start" as follows:</p>
<p class="PropText">Print "This text contains";WordCount%(ByVal Text$);"words"</p>
<p class="Paragraph">Now, if you start the program again, the text will appear exactly as you entered it. The content of the variable could not be modified by the subroutine.</p>
<p class="TextInTable">When you create a new module, <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Basic automatically inserts a SUB Main. This is only a default name and has nothing to do with the order or the starting point of a <help:productname xmlns:help="http://openoffice.org/2000/help">%PRODUCTNAME</help:productname> Basic project. You may rename this SUB however you like.</p>
</span></th></tr></table>
<p class="Paragraph"/>
<p class="Head2">Variable Validity in Procedures and Modules or Outside of Modules</p>
<p class="Paragraph">If a variable is defined within a SUB or FUNCTION, it only remains valid until the procedure is exited, and is created anew if the SUB or FUNCTION is required again. This is known as a "local" defined variable. In many cases, however, it may be necessary to define a variable to be valid in all procedures, or even in all modules of all libraries. Or, you may wish to retain a variable even after a SUB or FUNCTION is exited. This property is controlled in a variable declaration via certain key words in the <span class="T1">Dim</span> statement.</p>
<p class="Head3">Declaring Variables Outside a SUB or FUNCTION</p>
<p class="PropText">DIM PUBLIC VarName As TYPENAME</p>
<p class="Paragraph">The variable is valid in all modules.</p>
<p class="PropText">DIM PRIVATE VarName As TYPENAME</p>
<p class="Paragraph">The variable is only valid in this module.</p>
<p class="PropText">DIM VarName As TYPENAME</p>
<p class="Paragraph">As above.</p>
<p class="Head3">Saving Variable Contents after Exiting a SUB or FUNCTION</p>
<p class="PropText">DIM STATIC VarName As TYPENAME</p>
<p class="Paragraph">The variable retains its value until the next time the FUNCTION or SUB is entered. Note that the declaration must exist, of course, within a SUB or FUNCTION.</p>
<p class="TextInTable">Please refer to the explanation of <help:link Id="66471" Eid="basicfehler" xmlns:help="http://openoffice.org/2000/help">Debugging</help:link>, which provides further examples of variable validity, and especially the possible errors that may occur when variables are used incorrectly.</p>
<p class="TextInTable"><help:key-word value="Recursive calls of SUBs and functions" tag="kw66513_1" xmlns:help="http://openoffice.org/2000/help"/>Recursive calls of SUBs and functions are not possible.</p>
